[drivers] Add mapping macros to map the top level api functions directly to the driver implementation#30
Conversation
There was a problem hiding this comment.
Pull request overview
Note
Copilot was unable to run its full agentic suite in this review.
This PR introduces “direct API mapping” so platform driver implementations can directly provide the top-level whal_<Type>_* symbols (bypassing vtables/dispatch), and updates board/platform macros and documentation accordingly.
Changes:
- Add per-driver mapping flags that (1) rename driver functions to the top-level API at definition sites and (2) compile out unused vtables/prototypes when mapping is enabled.
- Refactor platform “device” macros into separate
_REGMAPand_DRIVERmacros and update board initializers to match. - Add
WHAL_ENOTIMPLand update docs/board Makefiles to compile the correct sources when mapping is enabled.
Reviewed changes
Copilot reviewed 98 out of 98 changed files in this pull request and generated 1 comment.
Show a summary per file
| File | Description |
|---|---|
| wolfHAL/watchdog/stm32wb_wwdg.h | Guard watchdog driver prototypes/vtable decl when mapping is active |
| wolfHAL/watchdog/stm32wb_iwdg.h | Guard watchdog driver prototypes/vtable decl when mapping is active |
| wolfHAL/uart/stm32wb_uart_dma.h | Guard DMA-UART driver prototypes/vtable decl when mapping is active |
| wolfHAL/uart/stm32wb_uart.h | Guard polled UART driver prototypes/vtable decl for mapping variants |
| wolfHAL/uart/stm32h5_uart.h | Guard aliasing macros when mapping for STM32H5 is active |
| wolfHAL/uart/stm32f4_uart.h | Guard STM32F4 UART prototypes/vtable decl when mapping is active |
| wolfHAL/uart/stm32c0_uart.h | Guard aliasing macros when mapping for STM32C0 is active |
| wolfHAL/uart/pic32cz_uart.h | Guard PIC32CZ UART prototypes/vtable decl when mapping is active |
| wolfHAL/timer/systick.h | Add mapping guard and rename exported SysTick API to whal_SysTick_* |
| wolfHAL/supply/pic32cz_supc.h | Guard PIC32CZ SUPC prototypes/vtable decl when mapping is active |
| wolfHAL/spi/stm32wb_spi.h | Guard STM32WB SPI prototypes/vtable decl for mapping variants |
| wolfHAL/spi/stm32h5_spi.h | Guard STM32H5 SPI prototypes/vtable decl when mapping is active |
| wolfHAL/spi/stm32f4_spi.h | Guard STM32F4 SPI prototypes/vtable decl when mapping is active |
| wolfHAL/spi/stm32c0_spi.h | Guard STM32C0 SPI aliasing macros when mapping is active |
| wolfHAL/sensor/imu/bmi270_sensor.h | Guard BMI270 prototypes/vtable decl when mapping is active |
| wolfHAL/rng/stm32wb_rng.h | Guard STM32WB RNG prototypes/vtable decl when mapping is active |
| wolfHAL/rng/stm32h5_rng.h | Guard STM32H5 RNG prototypes/vtable decl when mapping is active |
| wolfHAL/platform/st/stm32wb55xx.h | Split device macros into _REGMAP and _DRIVER macros |
| wolfHAL/platform/st/stm32h563xx.h | Split device macros into _REGMAP and _DRIVER macros |
| wolfHAL/platform/st/stm32f411xx.h | Split device macros into _REGMAP and _DRIVER macros |
| wolfHAL/platform/st/stm32c031xx.h | Split device macros into _REGMAP and _DRIVER macros |
| wolfHAL/platform/microchip/pic32cz.h | Split device macros into _REGMAP and _DRIVER macros |
| wolfHAL/platform/arm/cortex_m7.h | Split SysTick device macro into _REGMAP and _DRIVER |
| wolfHAL/platform/arm/cortex_m4.h | Split SysTick/NVIC device macros into _REGMAP and _DRIVER |
| wolfHAL/platform/arm/cortex_m33.h | Split SysTick device macro into _REGMAP and _DRIVER |
| wolfHAL/platform/arm/cortex_m0plus.h | Split SysTick device macro into _REGMAP and _DRIVER |
| wolfHAL/irq/cortex_m4_nvic.h | Guard NVIC prototypes/vtable decl when mapping is active |
| wolfHAL/i2c/stm32wb_i2c.h | Guard STM32WB I2C prototypes/vtable decl when mapping is active |
| wolfHAL/gpio/stm32wb_gpio.h | Guard STM32WB GPIO prototypes/vtable decl for mapping variants |
| wolfHAL/gpio/stm32h5_gpio.h | Guard GPIO aliasing macros when mapping for STM32H5 is active |
| wolfHAL/gpio/stm32f4_gpio.h | Guard GPIO aliasing macros when mapping for STM32F4 is active |
| wolfHAL/gpio/stm32c0_gpio.h | Guard GPIO aliasing macros when mapping for STM32C0 is active |
| wolfHAL/gpio/pic32cz_gpio.h | Guard PIC32CZ GPIO prototypes/vtable decl when mapping is active |
| wolfHAL/flash/stm32wb_flash.h | Guard STM32WB flash prototypes/vtable decl when mapping is active |
| wolfHAL/flash/stm32h5_flash.h | Guard STM32H5 flash prototypes/vtable decl when mapping is active |
| wolfHAL/flash/stm32f4_flash.h | Guard STM32F4 flash prototypes/vtable decl when mapping is active |
| wolfHAL/flash/stm32c0_flash.h | Guard STM32C0 flash prototypes/vtable decl when mapping is active |
| wolfHAL/flash/spi_nor_flash.h | Guard SPI-NOR top-level-like API prototypes; keep 4-byte init unguarded |
| wolfHAL/flash/pic32cz_flash.h | Guard PIC32CZ flash prototypes/vtable decl when mapping is active |
| wolfHAL/eth_phy/lan8742a_eth_phy.h | Guard LAN8742A PHY prototypes/vtable decl when mapping is active |
| wolfHAL/eth/stm32h5_eth.h | Guard STM32H5 ETH prototypes/vtable decl when mapping is active |
| wolfHAL/error.h | Add WHAL_ENOTIMPL error code |
| wolfHAL/dma/stm32wb_dma.h | Guard STM32WB DMA prototypes/vtable decl when mapping is active |
| wolfHAL/crypto/stm32wb_aes.h | Guard STM32WB AES prototypes/vtable decl when mapping is active |
| wolfHAL/clock/stm32wb_rcc.h | Guard STM32WB RCC prototypes/vtable decl for PLL/MSI mapping variants |
| wolfHAL/clock/stm32h5_rcc.h | Guard STM32H5 RCC prototypes/vtable decl for PLL/HSI mapping variants |
| wolfHAL/clock/stm32f4_rcc.h | Guard STM32F4 RCC prototypes/vtable decl when mapping is active |
| wolfHAL/clock/stm32c0_rcc.h | Guard STM32C0 RCC prototypes/vtable decl when mapping is active |
| wolfHAL/clock/pic32cz_clock.h | Guard PIC32CZ clock prototypes/vtable decl when mapping is active |
| wolfHAL/block/sdhc_spi_block.h | Guard SDHC-SPI block driver prototypes/vtable decl when mapping is active |
| src/watchdog/stm32wb_wwdg.c | Add mapping rename block; compile out vtable when mapping is active |
| src/watchdog/stm32wb_iwdg.c | Add mapping rename block; compile out vtable when mapping is active |
| src/uart/stm32wb_uart_dma.c | Add mapping rename block; compile out vtable when mapping is active |
| src/uart/stm32wb_uart.c | Add mapping rename block; add async stubs for mapped polled UART |
| src/uart/stm32f4_uart.c | Add mapping rename block; add async not-impl stubs; compile out vtable when mapped |
| src/uart/pic32cz_uart.c | Add mapping rename block; add async not-impl stubs; compile out vtable when mapped |
| src/timer/systick.c | Add mapping rename block; rename SysTick_* to whal_SysTick_*; compile out vtable when mapped |
| src/supply/pic32cz_supc.c | Add mapping rename block; compile out vtable when mapping is active |
| src/spi/stm32wb_spi.c | Add mapping rename block; compile out vtable when mapping is active |
| src/spi/stm32h5_spi.c | Add mapping rename block; compile out vtable when mapping is active |
| src/spi/stm32f4_spi.c | Add mapping rename block; compile out vtable when mapping is active |
| src/sensor/imu/bmi270_sensor.c | Add mapping rename block; compile out vtable when mapping is active |
| src/rng/stm32wb_rng.c | Add mapping rename block; compile out vtable when mapping is active |
| src/rng/stm32h5_rng.c | Add mapping rename block; compile out vtable when mapping is active |
| src/irq/cortex_m4_nvic.c | Add mapping rename block; make functions non-static; compile out vtable when mapping is active |
| src/i2c/stm32wb_i2c.c | Add mapping rename block; compile out vtable when mapping is active |
| src/gpio/stm32wb_gpio.c | Add mapping rename block; compile out vtable when mapping is active |
| src/gpio/pic32cz_gpio.c | Add mapping rename block; compile out vtable when mapping is active |
| src/flash/stm32wb_flash.c | Add mapping rename block; compile out vtable when mapping is active |
| src/flash/stm32h5_flash.c | Add mapping rename block; compile out vtable when mapping is active |
| src/flash/stm32f4_flash.c | Add mapping rename block; compile out vtable when mapping is active |
| src/flash/stm32c0_flash.c | Add mapping rename block; compile out vtable when mapping is active |
| src/flash/spi_nor_flash.c | Add partial flash mapping rename block; compile out vtable when mapping is active |
| src/flash/pic32cz_flash.c | Add mapping rename block; compile out vtable when mapping is active |
| src/eth_phy/lan8742a_eth_phy.c | Add mapping rename block; compile out vtable when mapping is active |
| src/eth/stm32h5_eth.c | Add mapping rename block; compile out vtable when mapping is active |
| src/dma/stm32wb_dma.c | Add mapping rename block; make functions non-static; compile out vtable when mapping is active |
| src/crypto/stm32wb_aes.c | Add mapping rename block; compile out vtable when mapping is active |
| src/crypto/crypto.c | Compile out whal_Crypto_Init/Deinit wrappers when AES mapping is active |
| src/clock/stm32wb_rcc.c | Add mapping rename blocks; compile out vtables when mapping is active |
| src/clock/stm32h5_rcc.c | Add mapping rename blocks; compile out vtables when mapping is active |
| src/clock/stm32f4_rcc.c | Add mapping rename block; compile out vtable when mapping is active |
| src/clock/stm32c0_rcc.c | Add mapping rename block; compile out vtable when mapping is active |
| src/clock/pic32cz_clock.c | Add mapping rename block; compile out vtable when mapping is active |
| src/block/sdhc_spi_block.c | Add mapping rename block; compile out vtable when mapping is active |
| docs/writing_a_driver.md | Document direct API mapping pattern and new platform macro conventions |
| docs/getting_started.md | Document _REGMAP/_DRIVER macros and direct API mapping constraints |
| docs/adding_a_board.md | Update guidance for mapping flags and dispatch source selection |
| boards/stm32wb55xx_nucleo/board.c | Update device initializers to _REGMAP/_DRIVER and mapping-aware .driver usage |
| boards/stm32wb55xx_nucleo/Makefile.inc | Enable mapping flags and adjust compiled sources to avoid symbol collisions |
| boards/stm32h563zi_nucleo/board.c | Update device initializers to _REGMAP/_DRIVER and mapping-aware .driver usage |
| boards/stm32h563zi_nucleo/Makefile.inc | Enable mapping flags and adjust compiled sources to avoid symbol collisions |
| boards/stm32f411_blackpill/board.c | Update device initializers to _REGMAP/_DRIVER and mapping-aware .driver usage |
| boards/stm32f411_blackpill/Makefile.inc | Enable mapping flags and adjust compiled sources to avoid symbol collisions |
| boards/stm32c031_nucleo/board.c | Update device initializers to _REGMAP/_DRIVER and mapping-aware .driver usage |
| boards/stm32c031_nucleo/Makefile.inc | Enable mapping flags and adjust compiled sources to avoid symbol collisions |
| boards/pic32cz_curiosity_ultra/board.c | Update device initializers to _REGMAP/_DRIVER and mapping-aware .driver usage |
| boards/pic32cz_curiosity_ultra/Makefile.inc | Enable mapping flags and adjust compiled sources to avoid symbol collisions |
Comments suppressed due to low confidence (13)
wolfHAL/timer/systick.h:1
- This changes the public header API from
SysTick_*towhal_SysTick_*(the old symbols/prototypes are removed). If external users (or downstream boards) were callingSysTick_Init/Deinit/...directly, this is a breaking change. Consider adding compatibility aliases in the header (e.g.,#define SysTick_Init whal_SysTick_Init, etc.) or retaining the old prototypes as deprecated wrappers to avoid breaking downstream code.
wolfHAL/timer/systick.h:1 - This changes the public header API from
SysTick_*towhal_SysTick_*(the old symbols/prototypes are removed). If external users (or downstream boards) were callingSysTick_Init/Deinit/...directly, this is a breaking change. Consider adding compatibility aliases in the header (e.g.,#define SysTick_Init whal_SysTick_Init, etc.) or retaining the old prototypes as deprecated wrappers to avoid breaking downstream code.
wolfHAL/timer/systick.h:1 - This changes the public header API from
SysTick_*towhal_SysTick_*(the old symbols/prototypes are removed). If external users (or downstream boards) were callingSysTick_Init/Deinit/...directly, this is a breaking change. Consider adding compatibility aliases in the header (e.g.,#define SysTick_Init whal_SysTick_Init, etc.) or retaining the old prototypes as deprecated wrappers to avoid breaking downstream code.
wolfHAL/timer/systick.h:1 - This changes the public header API from
SysTick_*towhal_SysTick_*(the old symbols/prototypes are removed). If external users (or downstream boards) were callingSysTick_Init/Deinit/...directly, this is a breaking change. Consider adding compatibility aliases in the header (e.g.,#define SysTick_Init whal_SysTick_Init, etc.) or retaining the old prototypes as deprecated wrappers to avoid breaking downstream code.
wolfHAL/timer/systick.h:1 - This changes the public header API from
SysTick_*towhal_SysTick_*(the old symbols/prototypes are removed). If external users (or downstream boards) were callingSysTick_Init/Deinit/...directly, this is a breaking change. Consider adding compatibility aliases in the header (e.g.,#define SysTick_Init whal_SysTick_Init, etc.) or retaining the old prototypes as deprecated wrappers to avoid breaking downstream code.
src/irq/cortex_m4_nvic.c:1 - These functions were changed from
staticto external unconditionally. If the project ever needs to compile/link multiple NVIC implementations (or otherwise wants to keep these internal when not mapping), this increases the chance of symbol collisions and expands the exported surface area. A more robust pattern is to keep thesestaticwhenWHAL_CFG_IRQ_API_MAPPING_NVICis not defined, and only make them external in the mapping configuration (e.g., via aWHAL_API/WHAL_LOCALmacro or#ifdefaround thestatic).
src/irq/cortex_m4_nvic.c:1 - These functions were changed from
staticto external unconditionally. If the project ever needs to compile/link multiple NVIC implementations (or otherwise wants to keep these internal when not mapping), this increases the chance of symbol collisions and expands the exported surface area. A more robust pattern is to keep thesestaticwhenWHAL_CFG_IRQ_API_MAPPING_NVICis not defined, and only make them external in the mapping configuration (e.g., via aWHAL_API/WHAL_LOCALmacro or#ifdefaround thestatic).
src/irq/cortex_m4_nvic.c:1 - These functions were changed from
staticto external unconditionally. If the project ever needs to compile/link multiple NVIC implementations (or otherwise wants to keep these internal when not mapping), this increases the chance of symbol collisions and expands the exported surface area. A more robust pattern is to keep thesestaticwhenWHAL_CFG_IRQ_API_MAPPING_NVICis not defined, and only make them external in the mapping configuration (e.g., via aWHAL_API/WHAL_LOCALmacro or#ifdefaround thestatic).
src/irq/cortex_m4_nvic.c:1 - These functions were changed from
staticto external unconditionally. If the project ever needs to compile/link multiple NVIC implementations (or otherwise wants to keep these internal when not mapping), this increases the chance of symbol collisions and expands the exported surface area. A more robust pattern is to keep thesestaticwhenWHAL_CFG_IRQ_API_MAPPING_NVICis not defined, and only make them external in the mapping configuration (e.g., via aWHAL_API/WHAL_LOCALmacro or#ifdefaround thestatic).
wolfHAL/platform/st/stm32wb55xx.h:1 - With direct API mapping enabled, many driver vtables are compiled out (e.g.,
whal_Stm32wbUart_Driver), but_DRIVERmacros like this remain unconditionally defined and will expand to undefined symbols if accidentally used—leading to link-time failures that can be hard to diagnose. Consider making_DRIVERmacros conditional on the corresponding mapping flag (or defining them toNULL/ a sentinel and documenting it), so misuse is caught earlier and configurations are less error-prone.
wolfHAL/uart/stm32wb_uart.h:1 - The closing
#endifcomment doesn’t match the actual condition (it referencesWHAL_CFG_UART_API_MAPPING, but the guard is a multi-flag condition). Updating the comment to reflect the real condition would reduce confusion during maintenance/debugging.
wolfHAL/uart/stm32wb_uart.h:1 - The closing
#endifcomment doesn’t match the actual condition (it referencesWHAL_CFG_UART_API_MAPPING, but the guard is a multi-flag condition). Updating the comment to reflect the real condition would reduce confusion during maintenance/debugging.
src/uart/stm32f4_uart.c:1 - These async stubs are always compiled, even when
WHAL_CFG_UART_API_MAPPING_STM32F4is not enabled. In non-mapped builds, the generic dispatch likely determines async availability via vtable pointers, so these standalone functions can become dead/undocumented API surface. Consider wrapping these stubs in the same mapping guard used for renaming (like the STM32WB polled UART does), or explicitly documenting why they are intentionally exported even in non-mapped builds.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 98 out of 98 changed files in this pull request and generated 9 comments.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 100 out of 100 changed files in this pull request and generated no new comments.
Comments suppressed due to low confidence (7)
wolfHAL/uart/uart.h:1
- These comments state
SendAsync/RecvAsyncare NULL if unsupported, but several polled drivers in this PR populate these with stub functions that returnWHAL_ENOTIMPL. Please align the contract: either (a) keep these pointers NULL in vtable-based builds and rely on the dispatch layer returningWHAL_ENOTIMPL, or (b) update the comment/API documentation to explicitly allow non-NULL stubs for unsupported async.
src/uart/stm32wb_uart.c:1 - The async stub functions are always compiled and wired into the vtable, even in non-mapped (vtable-dispatch) builds. This adds code size and contradicts the header comment that async pointers are NULL when unsupported. Recommendation: only compile these stubs (and assign them) when direct API mapping is enabled; otherwise set
.SendAsync = NULLand.RecvAsync = NULLso the dispatch layer returnsWHAL_ENOTIMPLwithout extra call overhead. This same pattern appears in other UART drivers added in this PR.
src/uart/stm32wb_uart.c:1 - The async stub functions are always compiled and wired into the vtable, even in non-mapped (vtable-dispatch) builds. This adds code size and contradicts the header comment that async pointers are NULL when unsupported. Recommendation: only compile these stubs (and assign them) when direct API mapping is enabled; otherwise set
.SendAsync = NULLand.RecvAsync = NULLso the dispatch layer returnsWHAL_ENOTIMPLwithout extra call overhead. This same pattern appears in other UART drivers added in this PR.
wolfHAL/uart/stm32wb_uart.h:1 - The
#endifcomment referencesWHAL_CFG_UART_API_MAPPING, but the guard condition checks several mapping macros. Please update the comment to match the actual condition (e.g., mention the specific macros or use a generic description like/* UART direct API mapping disabled */) to avoid confusion during future edits.
wolfHAL/uart/stm32wb_uart.h:1 - The
#endifcomment referencesWHAL_CFG_UART_API_MAPPING, but the guard condition checks several mapping macros. Please update the comment to match the actual condition (e.g., mention the specific macros or use a generic description like/* UART direct API mapping disabled */) to avoid confusion during future edits.
wolfHAL/spi/stm32wb_spi.h:1 - The
#endifcomment (!WHAL_CFG_SPI_API_MAPPING) doesn't match the actual condition (WHAL_CFG_SPI_API_MAPPING_STM32WBandWHAL_CFG_SPI_API_MAPPING_STM32C0). Update the comment so it reflects the real preprocessor guard.
wolfHAL/spi/stm32wb_spi.h:1 - The
#endifcomment (!WHAL_CFG_SPI_API_MAPPING) doesn't match the actual condition (WHAL_CFG_SPI_API_MAPPING_STM32WBandWHAL_CFG_SPI_API_MAPPING_STM32C0). Update the comment so it reflects the real preprocessor guard.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
…tly to the driver implementation
No description provided.